home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.2 Development Libraries / SGI IRIX 6.2 Development Libraries.iso / dist / complib.idb / usr / share / catman / p_man / cat3 / complib / cgebal.z / cgebal
Text File  |  1996-03-14  |  4KB  |  133 lines
  1.  
  2.  
  3.  
  4. CCCCGGGGEEEEBBBBAAAALLLL((((3333FFFF))))                                                          CCCCGGGGEEEEBBBBAAAALLLL((((3333FFFF))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      CGEBAL - balance a general complex matrix A
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      SUBROUTINE CGEBAL( JOB, N, A, LDA, ILO, IHI, SCALE, INFO )
  13.  
  14.          CHARACTER      JOB
  15.  
  16.          INTEGER        IHI, ILO, INFO, LDA, N
  17.  
  18.          REAL           SCALE( * )
  19.  
  20.          COMPLEX        A( LDA, * )
  21.  
  22. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  23.      CGEBAL balances a general complex matrix A.  This involves, first,
  24.      permuting A by a similarity transformation to isolate eigenvalues in the
  25.      first 1 to ILO-1 and last IHI+1 to N elements on the diagonal; and
  26.      second, applying a diagonal similarity transformation to rows and columns
  27.      ILO to IHI to make the rows and columns as close in norm as possible.
  28.      Both steps are optional.
  29.  
  30.      Balancing may reduce the 1-norm of the matrix, and improve the accuracy
  31.      of the computed eigenvalues and/or eigenvectors.
  32.  
  33.  
  34. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  35.      JOB     (input) CHARACTER*1
  36.              Specifies the operations to be performed on A:
  37.              = 'N':  none:  simply set ILO = 1, IHI = N, SCALE(I) = 1.0 for i
  38.              = 1,...,N; = 'P':  permute only;
  39.              = 'S':  scale only;
  40.              = 'B':  both permute and scale.
  41.  
  42.      N       (input) INTEGER
  43.              The order of the matrix A.  N >= 0.
  44.  
  45.      A       (input/output) COMPLEX array, dimension (LDA,N)
  46.              On entry, the input matrix A.  On exit,  A is overwritten by the
  47.              balanced matrix.  If JOB = 'N', A is not referenced.  See Further
  48.              Details.  LDA     (input) INTEGER The leading dimension of the
  49.              array A.  LDA >= max(1,N).
  50.  
  51.      ILO     (output) INTEGER
  52.              IHI     (output) INTEGER ILO and IHI are set to integers such
  53.              that on exit A(i,j) = 0 if i > j and j = 1,...,ILO-1 or I =
  54.              IHI+1,...,N.  If JOB = 'N' or 'S', ILO = 1 and IHI = N.
  55.  
  56.      SCALE   (output) REAL array, dimension (N)
  57.              Details of the permutations and scaling factors applied to A.  If
  58.              P(j) is the index of the row and column interchanged with row and
  59.              column j and D(j) is the scaling factor applied to row and column
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. CCCCGGGGEEEEBBBBAAAALLLL((((3333FFFF))))                                                          CCCCGGGGEEEEBBBBAAAALLLL((((3333FFFF))))
  71.  
  72.  
  73.  
  74.              j, then SCALE(j) = P(j)    for j = 1,...,ILO-1 = D(j)    for j =
  75.              ILO,...,IHI = P(j)    for j = IHI+1,...,N.  The order in which
  76.              the interchanges are made is N to IHI+1, then 1 to ILO-1.
  77.  
  78.      INFO    (output) INTEGER
  79.              = 0:  successful exit.
  80.              < 0:  if INFO = -i, the i-th argument had an illegal value.
  81.  
  82. FFFFUUUURRRRTTTTHHHHEEEERRRR DDDDEEEETTTTAAAAIIIILLLLSSSS
  83.      The permutations consist of row and column interchanges which put the
  84.      matrix in the form
  85.  
  86.                 ( T1   X   Y  )
  87.         P A P = (  0   B   Z  )
  88.                 (  0   0   T2 )
  89.  
  90.      where T1 and T2 are upper triangular matrices whose eigenvalues lie along
  91.      the diagonal.  The column indices ILO and IHI mark the starting and
  92.      ending columns of the submatrix B. Balancing consists of applying a
  93.      diagonal similarity transformation inv(D) * B * D to make the 1-norms of
  94.      each row of B and its corresponding column nearly equal.  The output
  95.      matrix is
  96.  
  97.         ( T1     X*D          Y    )
  98.         (  0  inv(D)*B*D  inv(D)*Z ).
  99.         (  0      0           T2   )
  100.  
  101.      Information about the permutations P and the diagonal matrix D is
  102.      returned in the vector SCALE.
  103.  
  104.      This subroutine is based on the EISPACK routine CBAL.
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.